Using Precompiled Headers in C and C++

This section contains the following topics:

• "About Precompiled Headers"

• "Automatic Precompiled Header Processing"

• "Other Ways to Control Precompiled Headers"

• "PCH Performance Issues"

About Precompiled Headers

In effect, fec/fecc takes a snapshot of the state of the compilation at a particular point and writes it to a file before completing the compilation. When you recompile the same source file or another file with the same set of header files, the PCH mechanism recognizes the snapshot point, verifies that the corresponding PCH file is usable, and reads it back in.

The PCH mechanism can give you a dramatic improvement in compile-time performance. The trade-off is that PCH files may take a lot of disk space.

Automatic Precompiled Header Processing

• PCH File Requirements

• Reusing PCH files

• Obsolete File Deletion Mechanism

The PCH file contains a snapshot of all the code preceding the header stop point. The header stop point is typically the first token in the primary source file that does not belong to a preprocessing directive. The header stop point can also be specified directly by inserting a #pragma hdrstop. For example, consider the following C++ code:

#include "xxx.h"
#include "yyy.h"
int i;

#include "xxx.h"
#ifndef YYY_H
#define YYY_H 1
#include "yyy.h"
#endif
#if TEST
int i;
#endif

PCH File Requirements

A PCH file is produced only if the header stop point and the code preceding it (generally the header files themselves) meet the following requirements:

• The header stop point must appear at file scope; it may not be within an unclosed scope established by a header file. For example, a PCH file is not created in the following case:

  // xxx.h

  class A {

  // xxx.C

  #include "xxx.h"

  int i; };

• The header stop point can not be inside a declaration started within a header file, and it can not be part of a declaration list of a linkage specification. For example, a PCH file is not created in the following case:

  // yyy.h

  static

  // yyy.C

  #include "yyy.h"

  int i;

  In this case, the header stop point is int i, but since it is not the start of a new declaration, a PCH file is not created

• The header stop point can not be inside a #if block or a #define started within a header file.

• The processing preceding the header stop must not have produced any errors. (Note that warnings and other diagnostics are not reproduced when the PCH file is reused.)

• References to predefined macros __DATE__ or __TIME__ must not have appeared.

• Use of the #line preprocessing directive must not have appeared.

• #pragma no_pch must not have appeared.

When a precompiled header file is produced, in addition to the snapshot of the compiler state, it contains some information that can be checked to determine under what circumstances it can be reused. This information includes the following:

• The compiler version, including the date and time the compiler was built.

• The current directory (in other words, the directory in which the compilation is occurring).

• The command line options.

• The initial sequence of preprocessing directives from the primary source file, including #include directives.

• The date and time of the header files specified in #include directives.

For example, consider the following C++ code:

// a.C 
#include "xxx.h" 

...              // Start of code

// b.C 
#include "xxx.h" 

...              // Start of code

It may be that more than one PCH file is applicable to a given compilation. If so, the largest (in other words, the one representing the most preprocessing directives from the primary source file) is used. For instance, consider a primary source file that begins with the following code:

#include "xxx.h" 
#include "yyy.h" 
#include "zzz.h"

When a precompiled header file is created, it takes the name of the primary source file, with the suffix replaced by "pch." Unless -pch_dir is specified, the PCH file is created in the directory of the primary source file.

When a precompiled header file is created or used, a message similar to the following is issued:

"test.C": creating precompiled header file "test.pch"

In automatic mode (when -pch is used), fec/fecc considers a PCH file obsolete and deletes it under the following circumstances:

• The file is based on at least one out-of-date header file but is otherwise applicable for the current compilation.

• The file has the same base name as the source file being compiled (for example, xxx.pch and xxx.C) but is not applicable for the current compilation (for example, because of different command-line options).

Support for PCH processing is not available when multiple source files are specified in a single compilation. If the command line includes a request for precompiled header processing and specifies more than one primary source file, an error is issued and the compilation is aborted.

Other Ways to Control Precompiled Headers

• You can insert a #pragma hdrstop in the primary source file at a point prior to the first token that does not belong to a preprocessing directive. Thus you can specify where the set of header files subject to precompilation ends. For example,

  #include "xxx.h"

  #include "yyy.h"

  #pragma hdrstop

  #include "zzz.h"

  In this case, the precompiled header file includes the processing state for xxx.h and yyy.h but not zzz.h. (This is useful if you decide that the information added by what follows the #pragma hdrstop does not justify the creation of another PCH file.)

• You can use a #pragma no_pch to suppress the precompiled header processing for a given source file.

• You can use the command-line option -pch_dir directoryname to specify the directory in which to search for and/or create a PCH file.

PCH Performance Issues

In general, writing out a precompiled header file doesn't cost much, even if it does not end up being used, and if it is used it almost always produces a significant speedup in compilation. The problem is that the precompiled header files can be quite large (from a minimum of about 250K bytes to several megabytes or more), and so you probably don't want many of them sitting around.

You can see that, despite the faster recompilations, precompiled header processing is not likely to be justified for an arbitrary set of files with nonuniform initial sequences of preprocessing directives. The greatest benefit occurs when a number of source files can share the same PCH file. The more sharing, the less disk space is consumed. With sharing, the disadvantage of large precompiled header files can be minimized without giving up the advantage of a significant speedup in compilation times.

To take full advantage of header file precompilation, you should reorder the #include sections of your source files and/or group the #include directives within a commonly used header file.

The fecc source provides an example of how this can be done. A common idiom is the following:

#include "fe_common.h" 
#pragma hdrstop 
#include ...

#include "fe_common.h" 
#include "decl_hdrs.h"
#pragma hdrstop 
#include ...

Different environments and different projects have different needs. You should, however, be aware that making the best use of the precompiled header support will require some experimentation and probably some minor changes to your source code.